Creating and Configuring a Draw Context

Once you've initialized a virtual device and selected a drawing engine capable of drawing to that device, you can call the QADrawContextNew function to create a new draw context. You pass the device and engine to that function, along with a drawing rectangle, a clipping region, and a set of draw context flags. The flags specify features of the new draw context. Listing 7 illustrates how to create a double-buffered draw context with z buffering.

Listing 7 Creating a draw context



 
TQADrawContext          *myDrawContext;



if (QADrawContextNew(&myDevice, &myRect, &myClip, myEngine, 

            kQAContext_DoubleBuffer, &myDrawContext) != kQANoErr) {

    /*Error! Could not create new draw context.*/

}

If QADrawContextNew succeeds, it returns the result code kQANoErr and sets the myDrawContext parameter to the new draw context. Otherwise, if an error occurs, QADrawContextNew returns some other result code and sets the myDrawContext parameter to the value NULL .

When you are finished using the new draw context, you should free the memory and other resources it uses by calling the QADrawContextDelete function.

QuickDraw 3D RAVE does not provide a function to reposition an existing draw context. If a window associated with a draw context is moved on the screen, you need to delete the existing draw context and create a new draw context at the new location. Similarly, QuickDraw 3D RAVE does not provide a function to change the clipping region of a draw context. If you want to change a clipping region, you need to delete the existing draw context and create a new draw context with the desired clipping region.

However, you can change a number of other features of a draw context without having to delete an existing draw context and create a new one. The features you can change are indicated by the state variables of the draw context. For example, to change the background color of a draw context to opaque black, you can use the code shown in Listing 8 .

Listing 8 Setting a draw context state variable



 
void MySetBackgroundToBlack (TQADrawContext *drawContext);

{

    QASetFloat(drawContext, kQATag_ColorBG_a, 1.0);

    QASetFloat(drawContext, kQATag_ColorBG_r, 0.0);

    QASetFloat(drawContext, kQATag_ColorBG_g, 0.0);

    QASetFloat(drawContext, kQATag_ColorBG_b, 0.0);

}

The QASetFloat function sets a draw context state variable that has a floating-point value. QuickDraw 3D RAVE provides functions to get and set state variables with floating-point, long integer, or pointer values.

See "Tags for State Variables" , for a complete description of the available draw context state variables.

The QASetFloat function is defined using a C language macro:



 
#define QASetFloat(drawContext,tag,newValue) \

                (drawContext)->setFloat (drawContext,tag,newValue)

During compilation, the QASetFloat call is replaced by code that directly calls the drawing engine's floating-point setting method. This allows you to achieve the highest possible performance when configuring a draw context.

Previous | QD3D Book | Overview | Chapter Contents | Next